/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.wsinfra.wsrm.storage;

/** This class pertains to storage operations related to the WSRM protocol.
    These include functions such as
    <br>(a) Storage of sent/received messages over a sequence.
    <br>(b) Processing acknowledgements for a given sequence from over a set
    of message numbers.
    <br>(c) Retrieving messages for retransmissions.
    <br>(d) Retrieving the message numbers for a given sequence that have
    not been acknowledged yet.
    <br>(e) Retrieval of the last message number for a sequence.

    @author Shrideep Pallickara, Sangmi Lee and Beytullah Yildiz
    $Date: 2005/07/29 22:41:30 $
    $Revision: 1.6 $
*/

public interface WsrmProtocolStorageOperations {


  /** Processes a set of acknowledgements received on a given sequence.
      This method throws an exception under the following conditions.
      <br> The Sequence specified in sequenceIdentifier is an unknown one.
      <br> One or more of the acknowledgements refer to non-existent message
      numbers.
      <br> Storage related problems */
  public void processAcknowledgementsOnSequence(String sequenceIdentifier,
						long[] ackMessageNumbers)
    throws WsrmStorageException;




  /** Processes an acknowledgement received on a given sequence for a specific
      message number.
      This method throws an exception under the following conditions.
      <br> The Sequence specified in sequenceIdentifier is an unknown one.
      <br> The acknowledgement refers to non-existent message number
      <br> Storage related problems */
  public void processAcknowledgementOnSequence(String sequenceIdentifier,
					       long ackMessageNumber)
    throws WsrmStorageException;




  /** Retrieves the list of message numbers that have NOT been acknowledged,
      up until the message number specified in <i>upUntilMessageNumber</i>
      This method throws an exception under the following conditions.
      <br> The Sequence specified in sequenceIdentifier is an unknown one.
      <br> The specified message number is a non-existent one.
      <br> Storage related problems  */
  public long[] getUnacknowledgedMessageNumbers(String sequenceIdentifier,
						long upUntilMessageNumber)
    throws WsrmStorageException;



  /** Retrieves the list of message numbers that have NOT been acknowledged
      for a given Sequence. The message numbers returned are those for which
      the ackInterval has expired. The <i>ackRequested</i> variable if it is
      <i> true</i> indicates that this constraint is no longer valid, and ALL
      message numbers that have not been acknowledged should be returned. This
      method throws an exception if the Sequence specified in
      <i>sequenceIdentifier</i> is an unknown one or if there are other
      storage problems. */
  public long[] getUnacknowledgedMessageNumbers(String sequenceIdentifier,
						boolean ackRequested)
    throws WsrmStorageException;


  /** Retrieves the list of message numbers that have been acknowledged
      This method throws WsrmStorageException.*/
  public long[] getAcknowledgedMessageNumbers(String sequenceIdentifier)
    throws WsrmStorageException;



  /** Retrieves the message number associated with the LastMessage in a
      given sequence. This method throws an exception if the Sequence
      specified in sequenceIdentifier is an unknown one or if there are
      storage related problems.
  public long getMessageNumberForLastMessage(String sequenceIdentifier)
    throws WsrmStorageException;
   */


  /** Retrieves the message number that was last assigned on a given
      sequence. This method throws an exception if the Sequence
      specified in sequenceIdentifier is an unknown one or if there are
      storage related problems.  */
  public long getMessageNumberLastAssigned(String sequenceIdentifier)
    throws WsrmStorageException;


  /** Store a WSRM message to storage. This method throws an exception if
      there are storage related problems. */
  public void store(WsrmStorageWidget widget)
    throws WsrmStorageException;



  /** Checks to see if there are widgets that have been stored for the
      sequence in question. */
  public boolean hasStoredElements(String sequenceIdentifier)
    throws WsrmStorageException;


  /** Check to see if there is a widget that has been stored for a specific
      message number in a given Sequence */
  public boolean
  hasStoredElement(String sequenceIdentifier, long messageNumber)
    throws WsrmStorageException;

  /** Retrieves a stored WsrmStorageWidget from storage. This method throws an
      exception under the following conditions.
      <br> The Sequence specified in sequenceIdentifier is an unknown one.
      <br> The specified message number is a non-existent one.
      <br> Storage related problems  */
  public WsrmStorageWidget
  getStoredElement(String sequenceIdentifier,
		   long messageNumber) throws WsrmStorageException;



  /** Retrieves stored WsrmStorageWidgets from storage. This method throws an
      exception under the following conditions.
      <br> The Sequence specified in sequenceIdentifier is an unknown one.
      <br> One or more of the specified message numbers are non-existent.
      <br> Storage related problems */
  public WsrmStorageWidget[]
  getStoredElements(String sequenceIdentifier,
		   long[] messageNumbers) throws WsrmStorageException;


  /** Reset the ack interval associated with the message */
  public void resetAckInterval(WsrmStorageWidget wsrmStorageWidget,
			       long ackInterval)
    throws WsrmStorageException;
}
